Включения в повествование

При экспорте в другие форматы включения могут отображаться другим шрифтом, цветом, отделяться от основного содержимого произведения линией или фоном.

Пример простого текстового включения:

[(
Сумма квадратов катетов равна квадрату гипотенузы.
)]

И вот такой результат:

Типы включений

Общее правило: все включения ограничиваются парой из квадратной скобки и знака типа включения.

Включения бывают нескольких типов:

• [( )] текстовый блок;
• [= =] преформатированный текст;
• [& &] программный код;
• [% %] формулы;
• [| |] таблицы;
• [/ /] комментарии;
• [[ ]] медиа-включение;
• [` `] ноты;
• [" "] цитаты - всё-таки склоняюсь цитирование выделить в отдельное включение и добавить строчный вариант.

- [* *] видео и аудио в отдельное включение, тогда проще с классами изображений решить

- [{ }] псевдо-включение (группирующее) включение; //??включения - колонки - как альтернатива таблицам

[~ ~] ссылка;

- [§ §] оглавление.

Схема блочного включения (на примере текстового блока)

• Класс включения указывается после открывающейся скобки и знака включения. Вплотную без пробелов!
• Идентификатор включения начинается со знака решётка #, отделяется пробелом. Идентификатор должен быть уникальным для всего произведения.
• Название указывается после класса и идентификатора, через пробел.
• Описание включения указывается после закрывающей скобки.

[(class #id Name
Тело включения
)] Description

Все эти атрибуты включения необязательны и указываются только при необходимости.

Между включениями и после включения вставляется пустая строка (для облегчения восприятия).

Все включения имеют такое блочное представление, а некоторые включения могут применяться и в строке.

Рассмотрим все элементы включений на примере текстового включения.

Название включения

Название располагается после открывающих скобок ( и после идентификатора, если он есть) через пробел.

[( Интересный факт №23
Нил замерзал дважды — в IX и XI веках.
)]

Вот результат:

Идентификатор включения

Идентификатор обозначается знаком # (решётка) и отделяется пробелом. Может состоять из прописных букв a-z, цифр 0-9, разделителей - (минус) и _ (подчеркивание).

В данном примере идентификатор: g-5.

[( #g-5 Экзаменационный вопрос №5
Может ли проверка правильности решения задачи быть более длительной, чем само получение решения, независимо от алгоритма проверки?
)]

Идентификатор может быть полезен, например, для для связывания задачи с ответом. Идентификатор должен быть уникален для всего текста.

Класс включения

Класс указывает на некую общность всех включений этого класса. При конвертации такие включения могут, например, выделяться цветом.

Класс включения указывается сразу после обозначения включения без пробелов. Может состоять из прописных букв a-z, цифр 0-9, разделителей - (минус) и _ (подчеркивание).

В данном примере класс: warning.

[(warning Предупреждение об опасности
При использовании угловой отрезной машинки обязательно **надевайте защитные очки**!
)]

Зарезервированные классы и сокращения классов

Существуют зарезервированные классы, несущие распространенную смысловую нагрузку. Используя эти классы вы получите предсказуемый результат в различных программах конвертирующих маркван-текст в иной формат.

Кроме того, есть возможность короткого написания классов. Для warning это !!. Плюсы сокращений в том, что они быстрее пишутся и не зависят от знания английского языка пользователем.

Список классов и их сокращений для тестового включения:

• i — note — примечание (вспомогательная информация, комментарий, разъяснение) (синий) i в кружке, мелкий шрифт
• ! — advise — совет (зеленый) лампочка
• !! — warning — предупреждение (жёлтый) ! в треугольнике
• !!! — danger — указание на опасность или ошибку (красный) огонь, шестиугольник
• ? — quest — вопрос(задание, упражнение)
• > — result — результат (выполнения кода или ответ к задаче (процесс решения))
• _ — hidden — скрытое (в интерактивных системах свернуто по умолчанию, в обычных может быть мелким шрифтом или "кверх ногами")
• " — quote — цитата
• e — epigraph — эпиграф.

В следующем примере знак ! равносилен advise (совет).

[(!
Мойте руки перед едой!
)]

Такие блоки при конвертации в другие форматы можно выделять цветами/иконками/заголовками/нестандартным выравниванием и т.п.

Классы для поэзии и постановок

Есть произведения с определенной спецификой форматирования, которые обозначаются специальными зарезервированными классами:

• poem — стих, поэма
• piece — пьеса
• screenplay — сценарий

Тело текстового включения

Внутри текстового блока используются все приёмы работы с текстом, такие как жирность или курсив. В текстовые блоки можно добавлять и другие включения, например, изображения, таблицы, код и т.п.

Текстовый блок не может использоваться строчно (т.к. это не имеет смысла).

Описание включения

Описание включения используется редко, в основном для расшифровки схем или пояснений к рисункам.

[[ Способы соединения мауэрлата
>Включения/img/Мауэрлат.png
]] а) Уголок; б) Болты; в) Стропило; г) Брус-стяжка; д) Мауэрлат; е) Гидроизоляция; ж) Несущая стена; з) Шпилька.

Этот тип включения будет рассмотрен в следующем разделе.